home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1999 April: Mac OS SDK / Dev.CD Apr 99 SDK1.toast / Development Kits / Interfaces&Libraries / Universal / Interfaces / PInterfaces / NetSprocket.p < prev    next >
Encoding:
Text File  |  1998-08-17  |  14.0 KB  |  397 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        NetSprocket.p
  3.  
  4.      Contains:    Games Sprockets: NetSprocket interfaces
  5.  
  6.      Version:    Technology:    NetSprocket 1.0.2
  7.                  Release:    Universal Interfaces 3.2
  8.  
  9.      Copyright:    © 1996-1998 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. }
  17. {$IFC UNDEFINED UsingIncludes}
  18. {$SETC UsingIncludes := 0}
  19. {$ENDC}
  20.  
  21. {$IFC NOT UsingIncludes}
  22.  UNIT NetSprocket;
  23.  INTERFACE
  24. {$ENDC}
  25.  
  26. {$IFC UNDEFINED __NETSPROCKET__}
  27. {$SETC __NETSPROCKET__ := 1}
  28.  
  29. {$I+}
  30. {$SETC NetSprocketIncludes := UsingIncludes}
  31. {$SETC UsingIncludes := 1}
  32.  
  33. {$IFC UNDEFINED __CONDITIONALMACROS__}
  34. {$I ConditionalMacros.p}
  35. {$ENDC}
  36.  
  37. {$IFC TARGET_OS_MAC }
  38. {$IFC UNDEFINED __MACTYPES__}
  39. {$I MacTypes.p}
  40. {$ENDC}
  41. {$IFC UNDEFINED __EVENTS__}
  42. {$I Events.p}
  43. {$ENDC}
  44.  
  45. {$IFC UNDEFINED __OPENTRANSPORT__}
  46. {$I OpenTransport.p}
  47. {$ENDC}
  48. {$IFC UNDEFINED __OPENTPTINTERNET__}
  49. {$I OpenTptInternet.p}
  50. {$ENDC}
  51.  
  52. {$ENDC}  {TARGET_OS_MAC}
  53.  
  54.  
  55. {$PUSH}
  56. {$ALIGN POWER}
  57. {$LibExport+}
  58.  
  59. {$IFC TARGET_OS_MAC }
  60.  
  61. CONST
  62.     kNSpMaxPlayerNameLen        = 31;
  63.     kNSpMaxGroupNameLen            = 31;
  64.     kNSpMaxPasswordLen            = 31;
  65.     kNSpMaxGameNameLen            = 31;
  66.     kNSpMaxDefinitionStringLen    = 255;
  67.  
  68.  
  69. { NetSprocket basic types }
  70.  
  71. TYPE
  72.     NSpGameReference = ^LONGINT;
  73.     NSpProtocolReference = ^LONGINT;
  74.     NSpProtocolListReference = ^LONGINT;
  75.     NSpAddressReference = ^LONGINT;
  76.     NSpEventCode                        = SInt32;
  77.     NSpGameID                            = SInt32;
  78.     NSpPlayerID                            = SInt32;
  79.     NSpGroupID                            = NSpPlayerID;
  80.     NSpPlayerType                        = UInt32;
  81.     NSpFlags                            = SInt32;
  82.     NSpPlayerName                        = Str31;
  83. { Individual player info }
  84.     NSpPlayerInfoPtr = ^NSpPlayerInfo;
  85.     NSpPlayerInfo = RECORD
  86.         id:                        NSpPlayerID;
  87.         playerType:                NSpPlayerType;                            {  "type" in C }
  88.         name:                    Str31;
  89.         groupCount:                UInt32;
  90.         groups:                    ARRAY [0..0] OF NSpGroupID;
  91.     END;
  92.  
  93. { list of all players }
  94.     NSpPlayerEnumerationPtr = ^NSpPlayerEnumeration;
  95.     NSpPlayerEnumeration = RECORD
  96.         count:                    UInt32;
  97.         playerInfo:                ARRAY [0..0] OF NSpPlayerInfoPtr;
  98.     END;
  99.  
  100. { Individual group info }
  101.     NSpGroupInfoPtr = ^NSpGroupInfo;
  102.     NSpGroupInfo = RECORD
  103.         id:                        NSpGroupID;
  104.         playerCount:            UInt32;
  105.         players:                ARRAY [0..0] OF NSpPlayerID;
  106.     END;
  107.  
  108. { List of all groups }
  109.     NSpGroupEnumerationPtr = ^NSpGroupEnumeration;
  110.     NSpGroupEnumeration = RECORD
  111.         count:                    UInt32;
  112.         groups:                    ARRAY [0..0] OF NSpGroupInfoPtr;
  113.     END;
  114.  
  115. { Topology types }
  116.     NSpTopology                            = UInt32;
  117.  
  118. CONST
  119.     kNSpClientServer            = $00000001;
  120.  
  121. { Game information }
  122.  
  123. TYPE
  124.     NSpGameInfoPtr = ^NSpGameInfo;
  125.     NSpGameInfo = RECORD
  126.         maxPlayers:                UInt32;
  127.         currentPlayers:            UInt32;
  128.         currentGroups:            UInt32;
  129.         topology:                NSpTopology;
  130.         reserved:                UInt32;
  131.         name:                    Str31;
  132.         password:                Str31;
  133.     END;
  134.  
  135. { Structure used for sending and receiving network messages }
  136.     NSpMessageHeaderPtr = ^NSpMessageHeader;
  137.     NSpMessageHeader = RECORD
  138.         version:                UInt32;                                    {  Used by NetSprocket.  Don't touch this  }
  139.         what:                    SInt32;                                    {  The kind of message (e.g. player joined)  }
  140.         from:                    NSpPlayerID;                            {  ID of the sender  }
  141.         toID:                    NSpPlayerID;                            {  (player or group) id of the intended recipient (was "to)  }
  142.         id:                        UInt32;                                    {  Unique ID for this message & (from) player  }
  143.         when:                    UInt32;                                    {  Timestamp for the message  }
  144.         messageLen:                UInt32;                                    {  Bytes of data in the entire message (including the header)  }
  145.     END;
  146.  
  147. { NetSprocket-defined message structures }
  148.     NSpErrorMessagePtr = ^NSpErrorMessage;
  149.     NSpErrorMessage = RECORD
  150.         header:                    NSpMessageHeader;
  151.         error:                    OSStatus;
  152.     END;
  153.  
  154.     NSpJoinRequestMessagePtr = ^NSpJoinRequestMessage;
  155.     NSpJoinRequestMessage = RECORD
  156.         header:                    NSpMessageHeader;
  157.         name:                    Str31;
  158.         password:                Str31;
  159.         theType:                UInt32;
  160.         customDataLen:            UInt32;
  161.         customData:                SInt8;
  162.     END;
  163.  
  164.     NSpJoinApprovedMessagePtr = ^NSpJoinApprovedMessage;
  165.     NSpJoinApprovedMessage = RECORD
  166.         header:                    NSpMessageHeader;
  167.     END;
  168.  
  169.     NSpJoinDeniedMessagePtr = ^NSpJoinDeniedMessage;
  170.     NSpJoinDeniedMessage = RECORD
  171.         header:                    NSpMessageHeader;
  172.         reason:                    Str255;
  173.     END;
  174.  
  175.     NSpPlayerJoinedMessagePtr = ^NSpPlayerJoinedMessage;
  176.     NSpPlayerJoinedMessage = RECORD
  177.         header:                    NSpMessageHeader;
  178.         playerCount:            UInt32;
  179.         playerInfo:                NSpPlayerInfo;
  180.     END;
  181.  
  182.     NSpPlayerLeftMessagePtr = ^NSpPlayerLeftMessage;
  183.     NSpPlayerLeftMessage = RECORD
  184.         header:                    NSpMessageHeader;
  185.         playerCount:            UInt32;
  186.         playerID:                NSpPlayerID;
  187.         playerName:                NSpPlayerName;
  188.     END;
  189.  
  190.     NSpHostChangedMessagePtr = ^NSpHostChangedMessage;
  191.     NSpHostChangedMessage = RECORD
  192.         header:                    NSpMessageHeader;
  193.         newHost:                NSpPlayerID;
  194.     END;
  195.  
  196.     NSpGameTerminatedMessagePtr = ^NSpGameTerminatedMessage;
  197.     NSpGameTerminatedMessage = RECORD
  198.         header:                    NSpMessageHeader;
  199.     END;
  200.  
  201. { Different kinds of messages.  These can NOT be bitwise ORed together }
  202.  
  203. CONST
  204.     kNSpSendFlag_Junk            = $00100000;                    {  will be sent (try once) when there is nothing else pending  }
  205.     kNSpSendFlag_Normal            = $00200000;                    {  will be sent immediately (try once)  }
  206.     kNSpSendFlag_Registered        = $00400000;                    {  will be sent immediately (guaranteed, in order)  }
  207.  
  208.  
  209. { Options for message delivery.  These can be bitwise ORed together with each other,
  210.         as well as with ONE of the above }
  211.     kNSpSendFlag_FailIfPipeFull    = $00000001;
  212.     kNSpSendFlag_SelfSend        = $00000002;
  213.     kNSpSendFlag_Blocking        = $00000004;
  214.  
  215.  
  216. { Options for Hosting Joining, and Deleting games }
  217.     kNSpGameFlag_DontAdvertise    = $00000001;
  218.     kNSpGameFlag_ForceTerminateGame = $00000002;
  219.  
  220. { Message "what" types }
  221. { Apple reserves all negative "what" values (anything with bit 32 set) }
  222.     kNSpSystemMessagePrefix        = $80000000;
  223.     kNSpError                    = $FFFFFFFF;
  224.     kNSpJoinRequest                = $80000001;
  225.     kNSpJoinApproved            = $80000002;
  226.     kNSpJoinDenied                = $80000003;
  227.     kNSpPlayerJoined            = $80000004;
  228.     kNSpPlayerLeft                = $80000005;
  229.     kNSpHostChanged                = $80000006;
  230.     kNSpGameTerminated            = $80000007;
  231.  
  232.  
  233. { Special TPlayerIDs  for sending messages }
  234.     kNSpAllPlayers                = $00000000;
  235.     kNSpHostOnly                = $FFFFFFFF;
  236.  
  237.  
  238. { NetSprocket Error Codes }
  239.     kNSpInitializationFailedErr    = -30360;
  240.     kNSpAlreadyInitializedErr    = -30361;
  241.     kNSpTopologyNotSupportedErr    = -30362;
  242.     kNSpPipeFullErr                = -30364;
  243.     kNSpHostFailedErr            = -30365;
  244.     kNSpProtocolNotAvailableErr    = -30366;
  245.     kNSpInvalidGameRefErr        = -30367;
  246.     kNSpInvalidParameterErr        = -30369;
  247.     kNSpOTNotPresentErr            = -30370;
  248.     kNSpOTVersionTooOldErr        = -30371;
  249.     kNSpMemAllocationErr        = -30373;
  250.     kNSpAlreadyAdvertisingErr    = -30374;
  251.     kNSpNotAdvertisingErr        = -30376;
  252.     kNSpInvalidAddressErr        = -30377;
  253.     kNSpFreeQExhaustedErr        = -30378;
  254.     kNSpRemovePlayerFailedErr    = -30379;
  255.     kNSpAddressInUseErr            = -30380;
  256.     kNSpFeatureNotImplementedErr = -30381;
  257.     kNSpNameRequiredErr            = -30382;
  258.     kNSpInvalidPlayerIDErr        = -30383;
  259.     kNSpInvalidGroupIDErr        = -30384;
  260.     kNSpNoPlayersErr            = -30385;
  261.     kNSpNoGroupsErr                = -30386;
  262.     kNSpNoHostVolunteersErr        = -30387;
  263.     kNSpCreateGroupFailedErr    = -30388;
  264.     kNSpAddPlayerFailedErr        = -30389;
  265.     kNSpInvalidDefinitionErr    = -30390;
  266.     kNSpInvalidProtocolRefErr    = -30391;
  267.     kNSpInvalidProtocolListErr    = -30392;
  268.     kNSpTimeoutErr                = -30393;
  269.     kNSpGameTerminatedErr        = -30394;
  270.     kNSpConnectFailedErr        = -30395;
  271.     kNSpSendFailedErr            = -30396;
  272.     kNSpJoinFailedErr            = -30399;
  273.  
  274.  
  275.  
  276.  
  277. {***********************  Initialization  ***********************}
  278. FUNCTION NSpInitialize(inStandardMessageSize: UInt32; inBufferSize: UInt32; inQElements: UInt32; inGameID: NSpGameID; inTimeout: UInt32): OSStatus; C;
  279.  
  280.  
  281.  
  282. {*************************  Protocols  *************************}
  283. { Programmatic protocol routines }
  284. FUNCTION NSpProtocol_New(inDefinitionString: ConstCStringPtr; VAR outReference: NSpProtocolReference): OSStatus; C;
  285. PROCEDURE NSpProtocol_Dispose(inProtocolRef: NSpProtocolReference); C;
  286. FUNCTION NSpProtocol_ExtractDefinitionString(inProtocolRef: NSpProtocolReference; outDefinitionString: CStringPtr): OSStatus; C;
  287.  
  288. { Protocol list routines }
  289. FUNCTION NSpProtocolList_New(inProtocolRef: NSpProtocolReference; VAR outList: NSpProtocolListReference): OSStatus; C;
  290. PROCEDURE NSpProtocolList_Dispose(inProtocolList: NSpProtocolListReference); C;
  291. FUNCTION NSpProtocolList_Append(inProtocolList: NSpProtocolListReference; inProtocolRef: NSpProtocolReference): OSStatus; C;
  292. FUNCTION NSpProtocolList_Remove(inProtocolList: NSpProtocolListReference; inProtocolRef: NSpProtocolReference): OSStatus; C;
  293. FUNCTION NSpProtocolList_RemoveIndexed(inProtocolList: NSpProtocolListReference; inIndex: UInt32): OSStatus; C;
  294. FUNCTION NSpProtocolList_GetCount(inProtocolList: NSpProtocolListReference): UInt32; C;
  295. FUNCTION NSpProtocolList_GetIndexedRef(inProtocolList: NSpProtocolListReference; inIndex: UInt32): NSpProtocolReference; C;
  296.  
  297. { Helpers }
  298. FUNCTION NSpProtocol_CreateAppleTalk(inNBPName: Str31; inNBPType: Str31; inMaxRTT: UInt32; inMinThruput: UInt32): NSpProtocolReference; C;
  299. FUNCTION NSpProtocol_CreateIP(inPort: InetPort; inMaxRTT: UInt32; inMinThruput: UInt32): NSpProtocolReference; C;
  300.  
  301. {**********************  Human Interface  ***********************}
  302.  
  303. TYPE
  304. {$IFC TYPED_FUNCTION_POINTERS}
  305.     NSpEventProcPtr = FUNCTION(VAR inEvent: EventRecord): BOOLEAN;
  306. {$ELSEC}
  307.     NSpEventProcPtr = ProcPtr;
  308. {$ENDC}
  309.  
  310. FUNCTION NSpDoModalJoinDialog(inGameType: Str31; inEntityListLabel: Str255; VAR ioName: Str31; VAR ioPassword: Str31; inEventProcPtr: NSpEventProcPtr): NSpAddressReference; C;
  311. FUNCTION NSpDoModalHostDialog(ioProtocolList: NSpProtocolListReference; VAR ioGameName: Str31; VAR ioPlayerName: Str31; VAR ioPassword: Str31; inEventProcPtr: NSpEventProcPtr): BOOLEAN; C;
  312.  
  313. {********************  Hosting and Joining  *********************}
  314. FUNCTION NSpGame_Host(VAR outGame: NSpGameReference; inProtocolList: NSpProtocolListReference; inMaxPlayers: UInt32; inGameName: Str31; inPassword: Str31; inPlayerName: Str31; inPlayerType: NSpPlayerType; inTopology: NSpTopology; inFlags: NSpFlags): OSStatus; C;
  315. FUNCTION NSpGame_Join(VAR outGame: NSpGameReference; inAddress: NSpAddressReference; inName: Str31; inPassword: Str31; inType: NSpPlayerType; inCustomData: UNIV Ptr; inCustomDataLen: UInt32; inFlags: NSpFlags): OSStatus; C;
  316. FUNCTION NSpGame_EnableAdvertising(inGame: NSpGameReference; inProtocol: NSpProtocolReference; inEnable: BOOLEAN): OSStatus; C;
  317. FUNCTION NSpGame_Dispose(inGame: NSpGameReference; inFlags: NSpFlags): OSStatus; C;
  318. FUNCTION NSpGame_GetInfo(inGame: NSpGameReference; VAR ioInfo: NSpGameInfo): OSStatus; C;
  319. {*************************  Messaging  *************************}
  320. FUNCTION NSpMessage_Send(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader; inFlags: NSpFlags): OSStatus; C;
  321. FUNCTION NSpMessage_Get(inGame: NSpGameReference): NSpMessageHeaderPtr; C;
  322. PROCEDURE NSpMessage_Release(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader); C;
  323. { Helpers }
  324. FUNCTION NSpMessage_SendTo(inGame: NSpGameReference; inTo: NSpPlayerID; inWhat: SInt32; inData: UNIV Ptr; inDataLen: UInt32; inFlags: NSpFlags): OSStatus; C;
  325.  
  326. {********************  Player Information  *********************}
  327. FUNCTION NSpPlayer_GetMyID(inGame: NSpGameReference): NSpPlayerID; C;
  328. FUNCTION NSpPlayer_GetInfo(inGame: NSpGameReference; inPlayerID: NSpPlayerID; VAR outInfo: NSpPlayerInfoPtr): OSStatus; C;
  329. PROCEDURE NSpPlayer_ReleaseInfo(inGame: NSpGameReference; inInfo: NSpPlayerInfoPtr); C;
  330. FUNCTION NSpPlayer_GetEnumeration(inGame: NSpGameReference; VAR outPlayers: NSpPlayerEnumerationPtr): OSStatus; C;
  331. PROCEDURE NSpPlayer_ReleaseEnumeration(inGame: NSpGameReference; inPlayers: NSpPlayerEnumerationPtr); C;
  332. FUNCTION NSpPlayer_GetRoundTripTime(inGame: NSpGameReference; inPlayer: NSpPlayerID): UInt32; C;
  333. FUNCTION NSpPlayer_GetThruput(inGame: NSpGameReference; inPlayer: NSpPlayerID): UInt32; C;
  334.  
  335. {********************  Group Management  *********************}
  336. FUNCTION NSpGroup_New(inGame: NSpGameReference; VAR outGroupID: NSpGroupID): OSStatus; C;
  337. FUNCTION NSpGroup_Dispose(inGame: NSpGameReference; inGroupID: NSpGroupID): OSStatus; C;
  338. FUNCTION NSpGroup_AddPlayer(inGame: NSpGameReference; inGroupID: NSpGroupID; inPlayerID: NSpPlayerID): OSStatus; C;
  339. FUNCTION NSpGroup_RemovePlayer(inGame: NSpGameReference; inGroupID: NSpGroupID; inPlayerID: NSpPlayerID): OSStatus; C;
  340. FUNCTION NSpGroup_GetInfo(inGame: NSpGameReference; inGroupID: NSpGroupID; VAR outInfo: NSpGroupInfoPtr): OSStatus; C;
  341. PROCEDURE NSpGroup_ReleaseInfo(inGame: NSpGameReference; inInfo: NSpGroupInfoPtr); C;
  342. FUNCTION NSpGroup_GetEnumeration(inGame: NSpGameReference; VAR outGroups: NSpGroupEnumerationPtr): OSStatus; C;
  343. PROCEDURE NSpGroup_ReleaseEnumeration(inGame: NSpGameReference; inGroups: NSpGroupEnumerationPtr); C;
  344.  
  345. {*************************  Utilities  **************************}
  346. FUNCTION NSpGetVersion: NumVersion; C;
  347. PROCEDURE NSpClearMessageHeader(VAR inMessage: NSpMessageHeader); C;
  348. FUNCTION NSpGetCurrentTimeStamp(inGame: NSpGameReference): UInt32; C;
  349. FUNCTION NSpConvertOTAddrToAddressReference(VAR inAddress: OTAddress): NSpAddressReference; C;
  350. FUNCTION NSpConvertAddressReferenceToOTAddr(inAddress: NSpAddressReference): OTAddressPtr; C;
  351. PROCEDURE NSpReleaseAddressReference(inAddress: NSpAddressReference); C;
  352.  
  353. {*********************** Advanced/Async routines ***************}
  354.  
  355. TYPE
  356. {$IFC TYPED_FUNCTION_POINTERS}
  357.     NSpCallbackProcPtr = PROCEDURE(inGame: NSpGameReference; inContext: UNIV Ptr; inCode: NSpEventCode; inStatus: OSStatus; inCookie: UNIV Ptr);
  358. {$ELSEC}
  359.     NSpCallbackProcPtr = ProcPtr;
  360. {$ENDC}
  361.  
  362. FUNCTION NSpInstallCallbackHandler(inHandler: NSpCallbackProcPtr; inContext: UNIV Ptr): OSStatus; C;
  363.  
  364.  
  365. TYPE
  366. {$IFC TYPED_FUNCTION_POINTERS}
  367.     NSpJoinRequestHandlerProcPtr = FUNCTION(inGame: NSpGameReference; VAR inMessage: NSpJoinRequestMessage; inContext: UNIV Ptr; VAR outReason: Str255): BOOLEAN;
  368. {$ELSEC}
  369.     NSpJoinRequestHandlerProcPtr = ProcPtr;
  370. {$ENDC}
  371.  
  372. FUNCTION NSpInstallJoinRequestHandler(inHandler: NSpJoinRequestHandlerProcPtr; inContext: UNIV Ptr): OSStatus; C;
  373.  
  374.  
  375. TYPE
  376. {$IFC TYPED_FUNCTION_POINTERS}
  377.     NSpMessageHandlerProcPtr = FUNCTION(inGame: NSpGameReference; VAR inMessage: NSpMessageHeader; inContext: UNIV Ptr): BOOLEAN;
  378. {$ELSEC}
  379.     NSpMessageHandlerProcPtr = ProcPtr;
  380. {$ENDC}
  381.  
  382. FUNCTION NSpInstallAsyncMessageHandler(inHandler: NSpMessageHandlerProcPtr; inContext: UNIV Ptr): OSStatus; C;
  383.  
  384.  
  385. {$ENDC}  {TARGET_OS_MAC}
  386.  
  387. {$ALIGN RESET}
  388. {$POP}
  389.  
  390. {$SETC UsingIncludes := NetSprocketIncludes}
  391.  
  392. {$ENDC} {__NETSPROCKET__}
  393.  
  394. {$IFC NOT UsingIncludes}
  395.  END.
  396. {$ENDC}
  397.